////////////////////////////////////////////////////////////////////////////////
// Copyright 2010 Michael Schmalle - Teoti Graphix, LLC
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0 
// 
// Unless required by applicable law or agreed to in writing, software 
// distributed under the License is distributed on an "AS IS" BASIS, 
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and 
// limitations under the License
// 
// Author: Michael Schmalle, Principal Architect
// mschmalle at teotigraphix dot com
////////////////////////////////////////////////////////////////////////////////

package org.teotigraphix.swizplugin.registry
{

/**
 * The <strong>IExtension</strong> interface is a lightweight extension
 * descriptor for <code>IExtensionRegistry</code> extensions.
 * 
 * <p>The <strong>IExtension</strong> represents an item that has been
 * added to the <code>IExtensionRegistry</code> through 
 * <code>IExtensionRegistry#addExtension()</code> method.</p>
 * 
 * <p>The extension instance that is created, typically mirrors an
 * <code>IPluginExtension</code> instance that was declared as a child of an 
 * <code>IPlugin</code> in MXML or XML.</p>
 * 
 * <p>The SwizPlugin platform implements two different kinds of MXML 
 * <code>IPluginExtension</code> classes. The first implementation is the 
 * <code>PluginExtension</code> that uses <code>PluginOption</code> declarations
 * as child nodes. The second implementation is the <code>XMLPluginExtension</code>
 * which uses an <code>XMLList</code> to declare it's children.</P>
 * 
 * <p>The main difference between the two implementations of 
 * <code>IPluginExtension</code> is the XML allows for truly dynamic content
 * and loading of that content, the MXML version allows for strict typing
 * of options and content embedding and class references.</p>
 * 
 * @author Michael Schmalle
 * @copyright Teoti Graphix, LLC
 * @productversion 1.0
 * 
 * @see org.teotigraphix.swizplugin.api.IPlugin
 * @see org.teotigraphix.swizplugin.api.IPluginExtension
 * @see org.teotigraphix.swizplugin.core.PluginExtension
 * @see org.teotigraphix.swizplugin.core.XMLPluginExtension
 * @see org.teotigraphix.swizplugin.core.PluginOptions
 */
public interface IExtension
{
	//--------------------------------------------------------------------------
	//
	//  Properties
	//
	//--------------------------------------------------------------------------
	
	//----------------------------------
	//  contributor
	//----------------------------------
	
	/**
	 * Returns the <code>IBundle</code>'s <code>IContributor</code> instance.
	 */
	function get contributor():IContributor;
	
	//----------------------------------
	//  simpleID
	//----------------------------------
	
	/**
	 * Returns the String identifier after the extension point identifier.
	 * 
	 * <p>Example; Given the id <code>com.acme.trace.myTraceExtension</code>,
	 * this property returns <strong>myExtension</strong>.</p>
	 */
	function get simpleID():String; // "myTraceExtension"
	
	//----------------------------------
	//  namespaceID
	//----------------------------------
	
	/**
	 * Returns the namespace identifier, this might be an extension point 
	 * identifier.
	 * 
	 * <p>Example; Given the id <code>com.acme.trace.myTraceExtension</code>,
	 * this property returns <strong>com.acme.trace</strong>.</p>
	 */
	function get namespaceID():String; // "com.example.acme"
	
	//----------------------------------
	//  uniqueID
	//----------------------------------
	
	/**
	 * Returns the whole extension identifier.
	 * 
	 * <p>Example; Given the id <code>com.acme.trace.myTraceExtension</code>,
	 * this property returns <strong>com.acme.trace.myTraceExtension</strong>.</p>
	 */
	function get uniqueID():String; // "com.example.acme.myTraceExtension"
	
	//----------------------------------
	//  internalID
	//----------------------------------
	
	/**
	 * The internal registry id.
	 */
	function get internalID():int;
	
	//----------------------------------
	//  extensionPointID
	//----------------------------------
	
	/**
	 * Returns the extensions point identifier.
	 * 
	 * <p>Example; '<code>com.example.acme.myTraceExtension</code>'.</p>
	 */
	function get extensionPointID():String; // "com.example.acme.trace"
	
	//----------------------------------
	//  label
	//----------------------------------
	
	/**
	 * Returns the label of the extension, <code>name</code> in mxml.
	 */
	function get label():String;
	
	//----------------------------------
	//  extensionRegistry
	//----------------------------------
	
	/**
	 * Returns the extension's <code>IExtensionRegistry</code>.
	 */
	function get extensionRegistry():IExtensionRegistry;
	
	//--------------------------------------------------------------------------
	//
	//  Methods
	//
	//--------------------------------------------------------------------------
	
	/**
	 * Returns the first level of extension descriptor children of type 
	 * <code>IExtensionDescriptor</code>.
	 * 
	 * <pre>
	 * // get the extension by "uid"
	 * var extension:IExtension = extensionRegistry.
	 *     getExtension("com.acme.splash.startupSplash");
	 * 
	 * // get all the extension's children descriptors
	 * var descriptors:Array = extension.getExtensionDescriptors();
	 * 
	 * // output the unique id for each descriptor
	 * trace(IExtensionDescriptor(descriptors[0]).uid); // deployedSplash
	 * trace(IExtensionDescriptor(descriptors[1]).uid); // debuggerSplash
	 * </pre>
	 * 
	 * @return An Array of <code>IExtensionDescriptor</code> children or 
	 * <code>null</code> if the extension does not contain children.
	 */
	function getExtensionDescriptors():Array; // of IExtensionDescriptor
	
	/**
	 * Returns the first <code>IExtensionDescriptor</code> by tagName
	 * on the extension.
	 * 
	 * <p><strong>Note:</strong> This is a short cut method for simple
	 * extensions.</p>
	 * 
	 * <pre>
	 * // load the extension point
	 * var point:IExtensionPoint = extensionRegistry.
	 * 	getExtensionPoint("com.acme.splash");
	 * 		
	 * // get the extension "startupSplash" by uid from the extenion point
	 * var extension:IExtension = point.getExtension("startupSplash");
	 * 
	 * // get the first child descriptor with the tag name "splash"
	 * var descriptor:IExtensionDescriptor = extension.getChild("splash");
	 * 
	 * // output the "uid" of the first child descriptor
	 * trace(descriptor.uid); // deployedSplash
	 * </pre>
	 * 
	 * @param tagName A String indicating the first tag child to return.
	 * @return The first <code>IExtensionDescriptor</code> by tagName or
	 * <code>null</code> if the child does not exist.
	 */
	function getChild(tagName:String):IExtensionDescriptor;
}
}